Get Master Locations

Method: GET
/locations

As a Customer of iFoodDS, you can use the Get Master Locations API to query master locations from the iFoodDS Trace Exchange platform.

info

This endpoint is being refined and thus subject to change. These docs will update when changes are made.

Request

Type: application/json

Retrieving master locations via the API is done through paging. The request requires a series of query parameters which define the page that must be returned. These parameters must be supplied in the url when the get is executed in order to return the result set for the page being queried.

Query Parameters

Optional

page (number): The page index of the locations to return. The first page is index 0.
size (number): The number of results to return per page. Default value is 20.
id (UUID, repeatable): Matches any specified DII location ID (diiId).
gln (string, repeatable): Matches any specified gln value (IN match).
duns (string, repeatable): Matches any specified duns value (IN match).
locationCode (string, repeatable): Matches any specified resolved location code: the vendor code when set, otherwise the data-provider code.
alternateLocationId (string, repeatable): Matches any specified alternateLocationId value (IN match).
parentLocationId (string, repeatable): Matches any specified parentLocationId value (IN match).
locationName (string, repeatable): Matches any specified resolved location name: the vendor name when set, otherwise the data-provider name.
locationType (string, repeatable): Matches the stored location type case-insensitively.
businessUnit (string, repeatable): Matches any specified businessUnit value (IN match).
category (string, repeatable): Filters by LocationCategory. Accepts a display label (for example, Grocery Store) or an enum name (for example, RESTAURANT).
country (string, repeatable): Matches any specified country value (IN match).
state (string, repeatable): Matches any specified state value (IN match).
city (string, repeatable): Matches any specified city value (IN match).
postalCode (string, repeatable): Matches any specified postalCode value (IN match).
isCoveredByGdst (boolean): Filters by equality on isCoveredByGdst (true or false).
isPrimaryLocation (boolean): Filters by equality on isPrimaryLocation (true or false).
glnAssignedBy (string, repeatable): Matches any specified glnAssignedBy value (IN match).
submitStartDateTime (ISO local datetime): Includes only locations whose dateModified is on or after the specified date and time (inclusive).
submitEndDateTime (ISO local datetime): Includes only locations whose dateModified is on or before the specified date and time (inclusive).

Repeatable Filters

For filters marked repeatable, supply multiple values as a comma-separated list or repeat the query parameter. For example, id=<uuid1>,<uuid2> or id=<uuid1>&id=<uuid2>. IN matching returns records matching any supplied value for that filter.

Data Constraints

submitStartDateTime and submitEndDateTime use ISO local datetime values in the format yyyy-MM-ddTHH:mm:ss (for example, 2026-09-28T14:30:00).
Both date filters apply to dateModified, and both boundaries are inclusive.
Boolean filters accept true or false.

Response

Return result for the master locations queried.

{
    "content": [
        {
            "id": "<location id>",
            "gln": "<global location number>",
            "city": "<city>",
            "duns": "<duns number>",
            "state": "<state>",
            "country": "<country>",
            "geoFence": "<geo fence coordinates>",
            "postalCode": "<postal code>",
            "phoneNumber": "<phone number>",
            "businessUnit": "<business unit>",
            "locationCode": "<location code>",
            "locationName": "<location name>",
            "locationType": "<location type>",
            "glnAssignedBy": "<gln assigned by>",
            "gpsCoordinates": "<gps coordinates>",
            "streetAddress1": "<street address 1>",
            "streetAddress2": "<street address 2>",
            "isCoveredByGdst": <is covered by gdst>,
            "parentLocationId": "<parent location id>",
            "isPrimaryLocation": <is primary location>,
            "alternateLocationId": "<alternate location id>"
        }
    ],
    "pageable": {
        "pageNumber": <page number>,
        "pageSize": <page size>,
        "sort": {
            "unsorted": <is unsorted>,
            "sorted": <is sorted>,
            "empty": <is page empty>
        },
        "offset": <offset size>,
        "unpaged": <is unpaged>,
        "paged": <is paged>
    },
    "totalPages": <total pages>,
    "totalElements": <total elements>,
    "last": <is last page>,
    "numberOfElements": <number of elements>,
    "size": <page size>,
    "number": <page number>,
    "sort": {
        "unsorted": <is unsorted>,
        "sorted": <is sorted>,
        "empty": <is empty>
    },
    "first": <is first page>,
    "empty": <is page empty>
}

Content

id (uuid): The unique identifier for the location
gln (string): GS1 Global Location Number, a 13-digit string. GS1 GTIN Executive Summary
city (string): The city where the location is situated
duns (string): Data Universal Numbering System identifier
state (string): The state or province where the location is situated
country (string): The country where the location is situated
geoFence (string): A series of GPS coordinates that define the boundaries of the location
postalCode (string): The postal or ZIP code for the location
phoneNumber (string): Contact phone number for the location
businessUnit (string): The business unit associated with this location
locationCode (string): A unique code identifier for the location
locationName (string): The name of the location
locationType (string): The type of location
glnAssignedBy (string): The organization that assigned the GLN
gpsCoordinates (string): The GPS coordinates for the location
streetAddress1 (string): The primary street address
streetAddress2 (string): Additional address information (e.g., suite number)
isCoveredByGdst (boolean): Indicate if the location is part of GDST
parentLocationId (string): Identifier for the parent location, if this is a child location
isPrimaryLocation (boolean): Indicates if this is the primary location
alternateLocationId (string): Alternate ID of the location

Pageable

pageable (object)
- pageNumber (number): The current page number in the page series. Index 0 is first page
- pageSize (number): The number of events contained in the page
- offset (number): If there is an offset specified on there return results this will be populates. Default is 0
- unpaged (boolean): If the record set is unpaged then true else false
- paged (boolean): If the record set is paged then true else false
- sort (object)
  - unsorted (boolean): If the record set is unsorted then true else false
  - sorted (boolean): If the record set is sorted then true else false
  - empty (boolean): If the record set is empty then true else false
totalPages (number): The total amount of pages that contain all events in the query
totalElements (number): The total amount of events in the query
last (boolean): If the page is the last in the series then true else false
numberOfElements (number): The total amount of events in the table
size (number): The number of events contained in the page
number (number): The current page number in the page series
sort (object)
- unsorted (boolean): If the record set is unsorted then true else false
- sorted (boolean): If the record set is sorted then true else false
- empty (boolean): If the record set is empty then true else false
first (boolean): If the page is the first in the series then true else false
empty (boolean): If the page is empty then true else false

Sample Response

{
  "content": [
    {
      "id": "d96583b3-8cf9-43bb-9db3-02f060bb4a53",
      "gln": "1234567890123",
      "city": "Springfield",
      "duns": "123456789",
      "state": "IL",
      "country": "US",
      "geoFence": "40.28,-84.15,40.29,-84.14,40.27,-84.14",
      "postalCode": "62701",
      "phoneNumber": "+1-800-555-0199",
      "businessUnit": null,
      "locationCode": "CDC001",
      "locationName": "Central Distribution Center",
      "locationType": "Internal",
      "glnAssignedBy": "GS1",
      "gpsCoordinates": "86.271142,-79.593557",
      "streetAddress1": "123 Main St",
      "streetAddress2": "Suite 100",
      "isCoveredByGdst": false,
      "parentLocationId": "HQ001",
      "isPrimaryLocation": true,
      "alternateLocationId": null
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": {
      "unsorted": true,
      "sorted": false,
      "empty": true
    },
    "offset": 0,
    "unpaged": false,
    "paged": true
  },
  "totalPages": 22,
  "totalElements": 440,
  "last": false,
  "numberOfElements": 20,
  "size": 20,
  "number": 0,
  "sort": {
    "unsorted": true,
    "sorted": false,
    "empty": true
  },
  "first": true,
  "empty": false
}

Description of what user-fixable validation error occurred and in what part of the payload

  {
    "timestamp": "2024-12-08T20:47:54.096+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "<error description>"
  }

Request​

Query Parameters​

Optional​

Repeatable Filters​

Data Constraints​

Response​

Content​

Pageable​

Sample Response​